home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / win / pascal / ctl3d_p.exe / README.TXT < prev   
Encoding:
Text File  |  1993-03-18  |  10.1 KB  |  229 lines
  1. CTL3D.TXT
  2. ---------
  3.  
  4. Contents of this file:
  5.  
  6. What is CTL3D.PAS?
  7. Limitations imposed by CTL3D.DLL
  8. Using CTL3D in your applications
  9.    A Note on Dialog Resources
  10.    Using CTL3D for Windows 3.1 Only
  11.    Using CTL3D for Windows 3.0
  12. If You Have Problems
  13.  
  14. What is CTL3D.PAS?
  15. ------------------
  16.  
  17. This file gives guidance on how to use the CTL3D unit with Borland Pascal 7.0 (BP7)
  18. together with Microsoft's CTL3D.DLL to equip applications for using Microsoft-style 3D
  19. dialogs and message boxes.
  20.  
  21. The interface unit CTL3D.PAS takes care of all the interfacing needed with Microsoft's
  22. CTL3D DLL, for both Windows 3.0 and Windows 3.1.  If your application is designed to
  23. run only under Windows 3.1, changing it to use the 3D controls is as easy as including
  24. CTL3D in the Uses clause and changing just a few lines of code. Due to the nature of
  25. Microsoft's CTL3D.DLL, some more (fairly straightforward) work is required to use 3D
  26. controls if your application is also designed to run under Windows 3.0.
  27.  
  28. When you use the CTL3D interface unit in your applications, they will automatically
  29. detect the presence of CTL3D.DLL at run time, and provide 3D dialogs and message boxes
  30. if it is found. If CTL3D.DLL is not found, your application will revert to using the 
  31. standard look dialogs as defined in your resource files. If your application also
  32. uses BWCC, the use of CTL3D will not interfere: it will provide the Microsoft 3D-look
  33. for any common dialogs it uses, if you desire.
  34.  
  35. Limitations imposed by CTL3D.DLL
  36. ---------------------------------
  37.  
  38. While the CTL3D interface unit gives your applications access to all the facilities of
  39. the CTL3D DLL, that DLL has some inherent limitations as documented by Microsoft.
  40. Briefly, these are as follows:
  41.  
  42. (1) CTL3D.DLL will 'subclass' (that is, provide 3D appearance for) individual dialogs
  43.     and message boxes only for VGA-resolution (649x480) displays or higher.
  44. (2) CTL3D.DLL will allow an application to 'auto-subclass' (that is, automatically
  45.     provide 3D appearance for ALL that application's dialogs and message boxes) only
  46.     under Windows 3.1. It cannot do this when running under Windows 3.0.
  47.  
  48. Using CTL3D in your applications
  49. --------------------------------
  50.  
  51. The work you have to do to convert your applications to use CTL3D is not difficult. Just
  52. copy CTL3D.DLL to your windows/system directory and follow the instructions given below.
  53.  
  54. A Note on Dialog Resources
  55. --------------------------
  56.  
  57. CTL3D works with 'standard' dialog resources created via Borland's Resource Workshop or
  58. other resource editor, but not with BWCC dialogs (those using controls supported by
  59. Borland's BWCC.DLL). It will work with these resources unchanged, but you may find you
  60. need to 'tweak' some of them a little to compensate for the slightly changed control
  61. sizes introduced by the CTL3D DLL.
  62.  
  63. Using CTL3D for Windows 3.1 Only
  64. --------------------------------
  65.  
  66. If your application is designed for use only with Windows 3.1, you need only follow these
  67. simple steps:
  68.  
  69. (1) Include CTL3D in the appropriate Uses clauses.
  70.  
  71.     CTL3D needs to be included in the Uses clause of those program units which use the
  72.     TApplication object and the unit declaring your main TWindow or TMDIWindow object. Put
  73.     CTL3D anywhere in the Uses clauses *AFTER* any BWCC.
  74.  
  75. (2) Replace any direct reference to the following objects with the replacement shown (the
  76.     easiest way is to do a global replace on your source code):
  77.  
  78.       Replace                           With
  79.       -------                           ----
  80.       TApplication                      T3dApplication
  81.       TWindow                           T3dWindow
  82.       TMDIWindow                        T3dMDIWindow
  83.  
  84. (3) In your main application object's Init constructor, add three Boolean parameters to
  85.     the inherited object's Init call as follows:
  86.  
  87.     inherited Init (<AName>,True,True,True);    {where <AName> is your original parameter}
  88.                              ª    ª   ª
  89.                              ª    ª   ------ Use 3D common dialogs
  90.                              ª    ---------- Use 3D borders
  91.                              --------------- Auto-subclass all dialogs
  92.  
  93.     This will cause your application to give the 3D appearance and 3D border to all
  94.     dialogs, message boxes and common dialogs which do not already use the BWCC style.
  95.  
  96.     If you wish to restrict the use of 3D controls, change the appropriate Boolean
  97.     parameters shown above.
  98.  
  99. (4) If your main window object processes the wm_SysColorChange message, ensure its method
  100.     is named WMSysColorChange, and that it first calls its inherited method, thus:
  101.  
  102.     inherited WMSysColorChange(Msg);
  103.  
  104.     If your main window does not process the wm_SysColorChange message, you do *NOT* need
  105.     to do this!
  106.  
  107. Now recompile your application, and you should have the 3D dialogs working properly. If you
  108. experience problems, refer to the "If You Have Problems" topic at the end of this file.
  109.  
  110. Using CTL3D for Windows 3.0
  111. ---------------------------
  112.  
  113. If your application is designed to run under Windows 3.0 (whether or not it can run under
  114. Windows 3.1 as well), you need to perform a little more work. The reason for this is that
  115. CTL3D.DLL does not support the 'auto-subclassing' feature available under Windows 3.1 :-
  116. this means that you have to 'sub-class' each individual dialog and common dialog.
  117.  
  118. To prepare your application for using CTL3D, perform the following steps:
  119.  
  120. (1) Include CTL3D in the appropriate Uses clauses.
  121.  
  122.     CTL3D needs to be included in the Uses clause (*AFTER* any BWCC) of those program units
  123.     which declare any of the following:
  124.  
  125.     - the main Application object (derived from TApplication),
  126.     - the main window object (derived from TWindow or TMDIWindow),
  127.     - one or more dialog objects (derived from TDialog).
  128.  
  129.     Also, CTL3D needs to be included in the Uses clause of any program units which call any
  130.     of the common dialog functions.
  131.  
  132. (2) Replace any direct reference to the following objects with the replacement shown (the
  133.     easiest way is to do a global replace on your source code):
  134.  
  135.       Replace                           With
  136.       -------                           ----
  137.       TApplication                      T3dApplication
  138.       TWindow                           T3dWindow
  139.       TMDIWindow                        T3dMDIWindow
  140.       TDialog                           T3dDialog
  141.  
  142. (3) In your main application object's Init constructor, add three Boolean parameters to
  143.     the inherited object's Init call as follows:
  144.  
  145.     inherited Init (<AName>,True,True,True);    {where <AName> is your original parameter}
  146.                              ª    ª   ª
  147.                              ª    ª   ------ Use 3D common dialogs
  148.                              ª    ---------- Use 3D borders
  149.                              --------------- Auto-subclass all dialogs
  150.  
  151.     This will give your application the ability to give the 3D appearance and 3D border to
  152.     all dialogs, message boxes and common dialogs which do not already use the BWCC style.
  153.  
  154.     If you wish to restrict the use of 3D controls, change the appropriate Boolean
  155.     parameters shown above.
  156.  
  157. (4) If your main window object processes the wm_SysColorChange message, ensure its method
  158.     is named WMSysColorChange, and that it first calls its inherited method, thus:
  159.  
  160.     inherited WMSysColorChange(Msg);
  161.  
  162.     If your main window does not process the wm_SysColorChange message, you do *NOT* need
  163.     to do this!
  164.  
  165. (5) If any of your dialog objects process any of the following messages, you must ensure
  166.     the methods first call their inherited ancestors, thus:
  167.  
  168.     Message            Method Identifier       Insert call
  169.     -------            -----------------       -----------
  170.  
  171.     wm_CtlColor        WMCtlColor              inherited WMCtlColor(Msg);
  172.     wm_DlgBorder       WMDlgBorder             inherited WMDlgBorder(Msg);
  173.     wm_InitDialog      WMInitDialog            inherited WMInitDialog(Msg);
  174.     wm_NCActivate      WMNCActivate            inherited WMNCActivate(Msg);
  175.     wm_NCPaint         WMNCPaint               inherited WMNCPaint(Msg);
  176.     wm_SetText         WMSetText               inherited WMSetText(Msg);
  177.  
  178.  
  179. (6) If your application calls any of the common dialog functions listed below, and you wish
  180.     to use their 3D equivalents, you should replace the function names by those shown (the
  181.     names are all equivalent, except for the "3d" suffix. All parameters to the common
  182.     dialog functions remain unchanged:
  183.  
  184.     Original Name            Change To
  185.     -------------            ---------
  186.  
  187.     ChooseColor              ChooseColor3D
  188.     ChooseFont               ChooseFont3D
  189.     FindText                 FindText3D
  190.     GetOpenFilename          GetOpenFilename3D
  191.     GetSaveFilename          GetSaveFilename3D
  192.     PrintDlg                 PrintDlg3D
  193.     ReplaceText              ReplaceText3D
  194.  
  195. Now recompile your application, and you should have the 3D dialogs working properly. If you
  196. experience problems, refer to the "If You Have Problems" topic that follows.
  197.  
  198. If You Have Problems
  199. --------------------
  200.  
  201. If, when you run your modified application, none of your dialogs or message boxes appear 3D
  202. it is likely that CTL3D could not be found. You should copy CTL3D to your windows\system
  203. directory and then run your application again.
  204.  
  205. If your application is runnig under Windows 3.0 and your dialogs are not all properly shown
  206. in 3D, ensure your code does the following:
  207.  
  208. (a) Objects that were declared as ancestors of TDialog are now declared as ancestors of
  209.     T3dDialog.
  210. (b) Any dialog's methods that process the windows messages listed in (5) above call their
  211.     inherited equivalent (NB: do not use explicit qualification such as "TDialog.WMSetText".
  212.     You should use the  "inherited" keyword instead).
  213. (c) Any common dialog function call now uses the replacement function listed in (6) above.
  214.  
  215. --------------------------------------
  216. Steve Hamer-Moss,
  217. CoCo Systems Ltd., UK.
  218. March 1993.
  219.  
  220. EMail addresses:
  221.  
  222. Compuserve:  100034,1064
  223. CIX:         shammoss
  224.  
  225. and via Internet:
  226.  
  227. 100034.1064@compuserve.com      or
  228. shammoss@cix.compulink.co.uk
  229.